<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Help files</title>
<meta http-equiv="Content-Type" Content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../styles/styles.css">
<script language="javascript" src='../links.js' type="text/javascript"></script>
</head>


<body>
<h1>Help files</h1>
<div class=navbar>
<a href="../index.html">main</a> |
<a href="index.html">language and help files</a>
</div>

<h3>Help file syntax.</h3>

<div class=shortdescr>
The following control statements can be used in help files.
</div>

<table class="cont">
<tr class="cont"><th class="cont" width="40%">Control statement</th><th class="cont" width="60%">Description</th></tr>

  <tr class="cont"><td class="cont" width="40%">@Topic (at the beginning of a line)</td>
  <td class="cont" width="60%">
    Starts a topic definition. There are four topics with special names:
    <ol>
    <li>The topic with the name <dfn>Contents</dfn> has a special meaning. It is shown when
      <code>F1</code> is pressed in the FAR command line when the plugin is active or when an item
      is selected from the plugins help list.
    <li>If a plugin can be configured, it is recommended to specify
      <dfn>Config</dfn> as the name of the help topic for the configuration dialog.
      This topic will be shown when <code>F1</code> is pressed in the plugins configuration menu
      (Options|Plugins configuration).
    <li>If a plugin can be invoked both in the panels and in the editor or viewer and has different
      functions depending on where it was invoked, it is recommended to use topics
      <dfn>Editor</dfn> and <dfn>Viewer</dfn> for describing the operation in the viewer and
      editor, respectively. These topics will be shown when <code>Shift-F1</code> is pressed in the
      list of plugin commands in the viewer or editor.
    </ol>
  </td></tr>

  <tr class="cont"><td class="cont" width="40%">$Text (at the beginning of a line)</td>
  <td class="cont" width="60%">Defines a non-scrolling region. All lines starting with $ must be in
    the beginning of a topic (immediately after the line starting with @) and will be shown in a
    non-scrolling region, delimited from the rest of the text with a horizontal line.
  </td></tr>

  <tr class="cont"><td class="cont" width="40%">~Text~@Topic@</td>
  <td class="cont" width="60%">Reference to a topic. If you wish to access a topic from the main FAR
    Manager help from inside plugins help, precede the topic name with a colon ('<code>:</code>').<br>
    The reference must not be split on mutiple lines.
  </td></tr>

  <tr class="cont"><td class="cont" width="40%">~Text~@&lt;FullPath&gt;Topic@</td>
  <td class="cont" width="60%">Reference to a topic in a help file located at a folder with full or
    relative path of <dfn>FullPath</dfn>. An ending backslash must be added.<br>
    The reference must not be split on mutiple lines.<br>
    For example, the plugin Foo is located in folder 'D:\FAR\Plugins\Foo' and we need to show the
    topic 'FooInfo' from its help file.
    <pre class=code>~About Foo~@&lt;D:\FAR\Plugins\Foo\&gt;FooInfo@</pre>
  </td></tr>

  <tr class="cont"><td class="cont" width="40%">~Text~@&lt;FullModuleName&gt;Topic@</td>
  <td class="cont" width="60%">Reference to a topic in a help file located at the same folder as
    the plugin with the relative or full path of <dfn>FullModuleName</dfn>.<br>
    The reference must not be split on mutiple lines.<br>
    For example, we need to show the help topic 'FooInfo' from the help file of the plugin Foo
    'D:\FAR\Plugins\Foo\Foo.dll'.
    <pre class=code>~About Foo~@&lt;D:\FAR\Plugins\Foo\Foo.dll&gt;FooInfo@</pre>
  </td></tr>

  <tr class="cont"><td class="cont" width="40%">~Text~@URL@</td>
  <td class="cont" width="60%">URL activator, allowing to run applications that support URL
    protocols. The following list shows the protocols that can be used in help files:
<pre class=code>~File access protocol~@<b>file</b>://C:\Program Files\Far\License.txt@
~File transfer protocol~@<b>ftp</b>://ftp.kgb.ru/WinUtil/Rar/@
~HTTP~@<b>http</b>://plugring.farmanager.com/@
~MailTo~@<b>mailto</b>:vskirdin@@mail.ru@
~News~@<b>news</b>://fido7.far.support@
~Telnet~@<b>telnet</b>://fido7.far.support@</pre>
    The reference must not be split on mutiple lines.
   </td></tr>

  <tr class="cont"><td class="cont" width="40%">#Text#</div>
  <td class="cont" width="60%">Highlights the text <dfn>Text</dfn>.
  </td></tr>

  <tr class="cont"><td class="cont" width="40%">^ (at the beginning of a line or after $)</td>
  <td class="cont" width="60%">Centers the line.
  </td></tr>

  <tr class="cont"><td class="cont" width="40%">@- (at the beginning of a line)</td>
  <td class="cont" width="60%">Disables text auto format. By default FAR formats all lines in which
    text starts from the first position (is not indented). Must be placed in a separate line.
  </td></tr>

  <tr class="cont"><td class="cont" width="40%">@+ (at the beginning of a line)</td>
  <td class="cont" width="60%">Enables text auto format. Must be placed in a separate line.
  </td></tr>

  <tr class="cont"><td class="cont" width="40%">&lt;CtrlColorChar&gt;XX</td>
  <td class="cont" width="60%">Specifies a color attribute that will be used to
    display the text following it. The color attribute XX consists of two hexadecimal digits (0-9A-F).<br>
    For example, the backslash ('\') character is set to be the color specifying character
    (<dfn>&lt;CtrlColorChar&gt;</dfn>). Then the statement <code>\4F</code> will force the help
    manager to output the following text with white letters on dark red background.
    <br>(see <a href="control_statements.html#CtrlColorChar">CtrlColorChar</a>)
  </td></tr>

  <tr class="cont"><td class="cont" width="40%">&lt;CtrlColorChar&gt;-</td>
  <td class="cont" width="60%">Specifies that the following text must be displayed in default colors.
    <br>(see <a href="control_statements.html#CtrlColorChar">CtrlColorChar</a>)
  </td></tr>
</table>

<h3>Remarks</h3>
<div class=descr>
<ol>
<li>The length of a text string in a help file must not exceed 300 characters.<br>
<li>If you need to display the characters <b>~</b>, <b>#</b> or <b>@</b>,
    duplicate them (~~, ##, @@).
<li>In the &lt;URL&gt; field of URL activators, the <b>~</b> and <b>#</b> characters
    may be duplicated or specified once, but the <b>@</b> character must be always duplicated.
    If the URL must contain a sequence of two <b>~</b> or <b>#</b> characters, specify
    a sequence of 3 or 4 characters (for example, <b>~~~</b> and <b>~~~~</b> will be shown as
    <b>~~</b>).
<li>Don't use special characters <b>~</b>, <b>#</b> or <b>@</b> inside a reference that is not an URL activator.
</ol>
</div>

<h3>Example</h3>
<div class=descr>
  The following example is taken from the <code>FarEng.hlf</code> file.

<pre class=code>@FolderShortcuts
$ #Folder shortcuts#
    Folder shortcuts are designed to provide fast access to frequently
used folders. Press Ctrl-Shift-0..9, to create a shortcut
to the current folder. To change to the folder recorded in the shortcut,
press RightCtrl-0..9. If RightCtrl-0..9 pressed in edit line, it inserts
the shortcut path into the line.

    The #Show folder shortcuts# item in the <b>~Commands menu~@CmdMenu@</b> may be
used to view, set, edit and delete folder shortcuts.
</pre>

  It looks like this:<br>
  <img src="../../images/help1.gif" alt="" border="0" width="503" height="228">

<p>The following examples demonstrates usage of the URL activator.<br>
E-mail client activation:
<pre class=code>~vskirdin@@mail.ru~@mailto:vskirdin@@mail.ru@</pre>

<p>Browser activation:
<pre class=code>~http://plugring.farmanager.com/~@plugring.farmanager.com/@</pre>
or
<pre class=code>~http://www.uic.nnov.ru/~~ruiv/plugring/~@http://www.uic.nnov.ru/~ruiv/plugring/@</pre>


<p>The following example demonstrates usage of color attributes:<br>
<pre class=code>.Language=English,English
.PluginContents=Reversi - Game
<b>.Options CtrlColorChar=\</b>

...

@-
         Reversi, also known as Othello, is a strategy game
 <b>\70 B \-\2F W \-</b>  played by two players:  Black and
 <b>\2F W \-\70 B \-</b>  #White#.  It is played on an 8x8 board
         using 64 disks with different color on each side.
@+

</pre>
  It looks like this:<br>
  <img src="../../images/helpattr.gif" alt="" border="0" width="108" height="84">

</div>

<div class=see>See also:</div><div class=seecont>
<a href="control_statements.html">Control statements</a>,
<a href="language_files.html">Language files</a>
</div>

</body>
</html>
